On this page
Semantic Markup with HTML and ARIA is an essential part of building with accessibility in mind. There is a wide range of functionality in terms of accessibility provided by the browser that you will learn about when building more semantic markup.
In a modern JavaScript library, you might be used to stacking divs on top of each other (aka “div soup”) because it seems to all just work the same. Or you might already have an idea that this a bad practice, yet you’ve seen it all over the web.
In this workshop, you’ll learn how this approach presents barriers and leaves a lot accessibility opportunities on the table.
With a little extra know how, you can turn an accessibility mess into a structured page.
Once you learn these semantic markup and ARIA basics you can take them to any framework, application, or job and build more accessible projects.
But remember, no matter how you're building your website, it should be built with accessibility in mind. Users doesn't really care what framework or library your web app is built with. They care about their experience.
This workshop focuses on learning how to communicate what structure and relationships exist in your website through proper HTML elements (semantic markup) and ARIA use.
Throughout your coding journey, you will use several tools and test the user experience on multiple browsers and operating systems with a screen reader.
Semantic Markup and ARIA is the foundation of accessible structure. You can then build on top of it to create more complex, interactive, and rich accessible web applications.
Video Transcript
So here we are, our camp spots application that we're working with. This version of it uses react. And so we've really swapped out the internals to be much more JavaScript heavy.
And that's so that we can talk about some of the techniques that will come up when you're working in a JavaScript application, but really kind of the takeaway is that. It doesn't really matter how your website is built to end users. They're going to look at what's rendered, what's visible. How does it work?
How is it? Is it accessible? And so really the kind of takeaway number one is that no matter how you're building your website, it, it should be built with accessibility in mind. So let's start with the foundational concepts of that creating semantic markup. So we're looking at a pretty visual design that, you know, when I got these designs from our designer and Figma, I could have built them any number of ways and actually did build them the first time on purpose.
Very inaccessibly and some of the pages in this application are still built that way so that we can make them better. But when we're building it, we have to put some effort into creating the most semantic version of these webpages, so that assistive technology users, people using screen readers voice dictation, all different ways of navigating beyond using your eyeballs and a mouse.
There's a lot of benefit from creating a more semantic website. So we'll talk about what is that, how do we create that, especially with this more JavaScript driven approach, how can we ensure that what is getting output to be in front of users is something that actually has some accessible structure and accessible information to it.
Project Overview
In this workshop, you’ll work on the CampSpots web application. This site is built in React so you’ll get a chance to see what techniques and patterns come up when building out features and pages in a JavaScript-heavy environment (an area where accessibility is frequently forgotten or missed).
As mentioned above, regardless of the type of application you work on a bulk of these concepts will still apply if you are building any layouts or user interfaces (UI).
The workshop repository can be found on GitHub.
You can clone the repository locally using git and use yarn or npm to set it up on your local machine. This is the method that I use.
If you don’t feel like wrangling packages and doing a local setup, there’s an option to use GitPod. This tool provides a browser-based environment that is similar to running VSCode. Note that there may be some accessibility issues with this browser-based tooling.
There is also a deployed version of the CampSpots application for this workshop that you can view without running locally.
Video Transcript
We're going to talk about the foundations of creating accessible websites and web applications with a bit of code. You can also follow along and test some of these things. There is a deployed URL for this version of our application that you can find here on GitHub. So the workshop directory or repository for this project is under workshop-semantics-html-aria and that's where that README and all of our exercise files can be found.
So you've got a couple of options for these workshops. You can check this code out locally using git and run it on your local machine. You can also use this tool called gitpod to load this in the browser, in the cloud. And if you want a simple browser-based experience, that could be a good way to go.
you can do that as well. So following along, making changes yourself, you've got options.
So with that, let's take a bit of a tour of our projects.
Project Structure
Most of the files we’ll work with in this workshop are in the components directory.
Inside there are several files that you can play with and make changes.
This workshop has five different sections, each with its own exercises & challenges.
Inside of each of the exercise directories you will find examples of “before and after” that you can look at if you want to skip ahead.
Looking at package.json
The package.json file includes all of the dependencies and scripts for the application.
For this workshop, you’ll only need to use the start script to start the local Parcel development server.
Anatomy of the CampSpots React App
The CampSpots demo app is built using React.
There’s an index.html file that imports an index.js file:
<!-- excerpt from index.html -->
<body>
<div id="portal-root"></div>
<div id="app-root"></div>
<script type="module" src="index.js"></script>
</body>And the index.js file is where the React app kicks off by importing and rendering the App.js component:
import React from "react"
import ReactDOM from "react-dom"
import { App } from "./App"
const app = document.getElementById("app-root")
ReactDOM.render(<App />, app)The App.js file has a whole lot of stuff in it!
There are multiple components imported, including Reach Router and several different page-level components. There are also some different “before and after” versions of components based on the work we’ll do.
// imports from App.js
import React from "react"
import { Router } from "@reach/router"
import "./global-styles/variables.scss"
import "./global-styles/styles.scss"
import Header from "components/header"
import HomePage from "components/page-home"
import AboutPage from "components/page-about"
import CareersPage from "components/page-careers"
import TripIdeasPage from "components/page-trip-ideas"
import ListingsPage from "components/page-listings"
import Listing from "components/page-listing-detail"
import EventsPage from "components/page-events"
import PassesPage from "components/page-passes"
import SubmitListingPage from "components/page-submit-listing"
import HikesPage from "components/page-adventures-hikes"
import Exercise1ListingsPage from "./exercise1-headings-landmarks/page-listings"
import Exercise1ListingPage from "./exercise1-headings-landmarks/page-listing-detail"
import Exercise2ARIAListingPage from "./exercise2-what-is-aria/page-listing-detail"
import Exercise3NamesListingPage from "./exercise3-accessible-names/page-listing-detail"
import Exercise3NamesListingsPage from "./exercise3-accessible-names/page-listings"
import Exercise4A11yInfoListingPage from "./exercise4-programmatic-a11y-info/page-listing-detail"You can navigate through the project to find the code for each of the components being imported, or check them out as they come up in the workshop.
You might find that there are “in-between” cases of components that are not completely accessible. This gives us the chance to make changes and see what effects those have in the browser and screen readers.
Application and Code Overview
Below you’ll find an overview of what we will build. I’ll give you a tour of the application itself as well as the current state of the components on various pages.
You can familiarize yourself with each of the components and pages that we will work with and make more accessible down below!
Video Transcript
So this is our campspot's home page. It has a mega menu on it that we worked on in our manual testing workshops. So that's in pretty good shape. We won't be touching that so much. The homepage is doesn't have a whole lot going on. What we're primarily going to work on in this workshop is under plan your trip and the find a camping spot, the listings page.
So we've got a dynamic listings page here that uses react components, including for an individual listing. And I will warn you. Some of these images are placeholders for some of the campgrounds. I haven't quite made it out to every single one to go shoot my own photography yet. I've thought about it. But for an individual listing page, the structure is really what we're looking at beyond placeholder content.
So for example, cranberry lake, which is over by deception pass here in Washington, it's got a title, a location, a description, a number of amenities that you could find at this campsite and then a date picker to go and book a campsite. So we'll be looking at this page primarily today. Both this one and the listings page, where we came from, and there's plenty that could go wrong with semantics with these two pages.
And so we'll go from the more foundational things like headings and semantic structure into things that will set us up to be much more interactive, like in our date picker. So I'm thrilled that you're here to join me on this journey from taking something that's kind of visual and divs only into something that's much more interactive with a screen reader so with that, we've seen the pages that we're going to be working on our listings and our listing detail.
React as an Abstraction
If you don’t have experience with React, that’s okay!
The lessons you learn in this workshop are applicable wherever HTML and JavaScript are used.
React uses JSX, which is like a seamless combination of HTML with the power of JavaScript.
It also allows us to access and update state variables, iterate over data, and set properties (such as various ARIA attributes) all in one place.
Video Transcript
So within this listings page, if you're new to react what I like about it is that we have JavaScript available. So we have really powerful functions that we can call that iterate over arrays over json objects all kinds of things.
And we can use HTML and components seamlessly together in this templating language called JSX. That's what we're looking at right here. It combines HTML. So tags that we're familiar with, like div, H1, image, and we can use custom components like a dropdown list component, and we can pass custom props into it.
So options that the component can use. There's a few quirks that you should know about that are important. That do come up quite a bit, such as class name. So in our rendered code, that will be changed into the class attribute. But since classes are reserved word in JavaScript, they had to come up with something else.
So class name is what we use in JSX. Similarly, if you're binding a label element and. Instead of label for you would write label HTML for. So you might see that come up and yeah, what I, another thing I really like about JSX is that I can, we can work with state variables really easily. So for things like aria, which we'll work with in exercise two, we can do really powerful things for accessibility right here in our templates.
So that's why I enjoy working with it. I find without it some of the, some of the code that you have to write to manage all of the state manage all of the, the Dom or document object model, it's definitely doable, but it takes a lot more code. Whereas some of the code here is abstracted away from us.
We're pulling in the react library, so it's like, there's still code there, but we aren't having to write quite as much.
The CampSpots Listing Page
The Listing page of CampSpots is a great introduction of the power of React and JSX.
We have our listings.json file that holds the initial data to places people can camp. In the page component’s source code at components/page-listings.js we iterate over that data and insert nicely displayed listings programmatically rather than hard-coding each one.
Video Transcript
Let's go check out the code for these, since we're going to be working with these files today.
So these files starting with components. So we saw app.js. That's where all of our page components come in and then those individual pages pull in sub components. For example, our page listings.js pulls in a number of different components like it's pulling in some listings data. So we've got listings.json.
So this is a way that we can separate our content from our business logic, which really takes me back to using XML for stuff like this. Now we're much prefer to use json, it's a lot cleaner but we can go and use this JavaScript object notation, all of these keys. Become things that we can use in a JavaScript component.
So we can pull in images. This is where our amenities come from. We can iterate over this array of amenities, these strings in here. So the strings will then match with image assets that we have in this project. And so within listings, we pull in that data, we've got a series of components that are reusable such as the listing excerpt.
Which if we go back here to the browser, each one of these on listings is a listing excerpt. So kind of a reusable component. Whereas the static HTML version of this was very repetitive. It was a lot of the same thing kind of copied over and over again. And so it's really nice to be able to update a component and then have every instance of that component take the updates. There's some more complexity with that, obviously. Kind of refreshing to have reusable components.
so in this listings page we've got a number of tags that kind of wrap things like a div that wraps our header for the page. We'll take a look at that to see if there's something more semantic that we could choose.
And then within our repeated list of listing excerpts, that's where we're iterating over some data and figuring out how are we going to populate those.
Our listing excerpt is getting iterated over from our listings.json I had to do a little bit of magic to pull in images. So our project is being bundled together using a tool called parcel. And so some of the techniques in here are things that I had to do to get parcel, to kind of work the way I needed including loading images.
So I'm loading images from a directory. All of them, then our listings, and then I'm plucking out specific ones when they match a specific listing. So that's images.
The Listing Excerpt
The Listing Excerpt component at components/listing-excerpt is a component that is repeated for each item on the Listings page. It displays all the information from listings.json and adds a link to the individual listing detail page.
We will see how we can build accessible pages even when we have dynamic data being passed to listing-excerpt. In fact, dynamic data and programmatic templates mean we can impact accessibility once for a variety of instances.
Video Transcript
So the listing excerpt, that component, let's take a look at it. This is our reusable component that we repeat for each listing and it takes in data such as an ID any extra data, like, let's see, what do we iterate over?
I think images potentially, or those are separate. But it gives us this dynamic component that we can do lots of things with, oh, I guess data, it gets expanded into listing name, location, listing type, the excerpt and the amenities. So it's kind of a handle on a collection of things.
Then we can pull into our component. So each instance of this gets powered with unique. And that part's already set up. You don't need to write it. You don't even really need to understand it. I'm mostly just giving you a tour so that you know, that this is how things are working and we'll really be focused on the accessibility parts.
I can sort of let the react to wash over us, pick out the accessibility parts and I'll draw your attention to those important parts so that you don't need to worry too much about what the heck are we looking at with react?
The Listing Detail Page
A majority of our time working with semantics and ARIA will be on the Listing Detail page.
This is the detailed page that tells you everything about a campsite and has a date picker to book days for that camp site.
We will get into heading structure, landmark elements, ARIA, and more all on this page.
Source code is located at components/page-listing-detail.js.
Video Transcript
The next page, I want to show you is our listing page listing detail, which from listing excerpt, we have a link here. So this is kind of accessibility does come into play here and that our link component.
Is coming from reach router. So it, that is a wrapper around the anchor tag. It creates an a, it's an accessible anchor element with an href on it. So that's kind of translating into something that is accessible and, you know, keyboard accessible, all those things. But this is where our listing individual listing pages come from and we create them dynamically so that when I click this link, it tries to go to a URL.
That route is set up in our app.js file. So we've got the connection being made from our links to actually saying, Hey, show this listing template and populate it with this, with the data from this ID. So a bit of dynamic magic happening already set up for us, which is nice. So that, that takes us to.
Page-listing-detail.js, which is as deep as we're going to get page wise throughout our site, this kind of the, the little universe we'll live in for this workshop. So on page listing detail, it doesn't need to do quite as much magic to iterate over the listing excerpt, like we know which listing we're looking at on this page.
So it's a bit of a template that takes in props or options and. It matches them from our listings.json, that we saw a little earlier, and this one could use a lot of help from a semantic markup point of view. It's got a lot of divs a lot of things that could be more semantic. So this is the bulk of where we will spend our energy is here in the page listing detail.
We've got things like divs with icons in them. Some divs with text that, and maybe not even wrapped in anything that look conspicuously, like they could be something more semantic, not going to spill the beans quite, but we've got a calendar section as well as the images
The Date Picker Component
The most complex component we’ll work with in this workshop is the date picker.
This is a great opportunity for you see see how doing a bit of up front work enables us to programmatically output relevant information for screen reader users.
Video Transcript
Let's go look at our date picker within components that lives in the date picker directory. And there is a date picker JS. It has its own CSS file or SAS which is a version of CSS that I really enjoy. So any of the styles for the date picker live in here, but the, logic for our date picker, this one is a little bit meaty.
So bear with me. We're going to make some pretty hefty changes to this one later to make it more Semantic and more accessible to keyboards and screen readers because that stuff all kind of all goes hand in hand to some degree. So our date picker is definitely the most complex thing that we will do in this workshop.
So yeah, we'll, we'll work on that when we get into, I think exercise too. We'll start looking at the, at the date picker.
Okay, so a bit of a tour it's it goes from our most basic with divs that need to be more semantic into something much more complex with the date picker. And while you could pick a date picker off the shelf, and hope that it's accessible. I think there's a lot of utility in working with the code, even if it's.
It's a lot. It can be kind of intense to write a date picker. It's cool to know what goes into it and what to look for. If you are picking a date picker off the shelf, like what makes an accessible date picker. And so we'll spend some time playing with that. Even if it's an exercise that you might not necessarily repeat writing your own date picker, it's still good to know kind of what to look out for.